//! \file IMutex.h
//! \brief Defines the interface for mutual exclusion (mutex) implementations.
//!
//! A mutex provides mutual exclusion to critical sections between multiple
//! threads.  A critical section typically contains access to a shared
//! resource that must be allowed to complete without interruption.  This
//! servers as the consistent interface independent of operating system.
// -----------------------------------------------------------------------------
//! This program is free software; you can redistribute it and/or
//! modify it under the terms of the GNU General Public License
//! as published by the Free Software Foundation; either version 2
//! of the License, or (at your option) any later version.
//!
//! This program is distributed in the hope that it will be useful,
//! but WITHOUT ANY WARRANTY; without even the implied warranty of
//! MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
//! GNU General Public License for more details.
//!
//! You should have received a copy of the GNU General Public License
//! along with this program; if not, write to the Free Software Foundation,
//! Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
// -----------------------------------------------------------------------------

// Project Includes
#include "SystemTypes.h"

#ifndef dIMUTEX_H_
  #define dIMUTEX_H_

  namespace code_sheriff
  {

    //! \class IMutex IMutex.h "IMutex.h"
    //! \brief Defines the interface for mutual exclusion (mutex)
    //! implementations.
    //!
    //! A mutex provides mutual exclusion to critical sections between multiple
    //! threads.  A critical section typically contains access to a shared
    //! resource that must be allowed to complete without interruption.  This
    //! servers as the consistent interface independent of operating system.
    class IMutex
    {

      //========================================================================
      public:
      //========================================================================

        //! \brief Specifies a time out value to never wait for a mutex lock.
        //!
        //! If this value is passed as the time out argument for a mutex lock
        //! request, the call will never wait (block) waiting for the mutex
        //! to become ready.
        static const tTIME_MS TIMEOUT_IMMEDIATELY = 0;

        //! \brief Specifies a time out value to never time out waiting for a
        //! mutex lock.
        //!
        //! If this value is passed as the time out argument for a mutex lock
        //! request, the call will wait indefinitely (block) until the mutex
        //! becomes ready.
        static const tTIME_MS TIMEOUT_FOREVER     = 0xFFFFFFFF;

        //! \brief Requests mutual exclusion.
        //!
        //! Allows the calling process to attempt to gain mutual exclusion.
        //! When mutual exclusion is granted, the process can safely access the
        //! critical section.
        //!
        //! \param [in] Timeout
        //!   The maximum time interval (in milliseconds) to block the calling
        //!   process for while waiting for the lock to become available.
        //!
        //! \retval Error
        //!   Error code indicating the result of the requested operation.
        //!
        //! \b Example: \code
        //! CMutex MyMutex;
        //! MyMutex.lock(TIMEOUT_IMMEDIATELY);
        //! \endcode
        virtual TERROR lock(tTIME_MS Timeout) = 0;

        //! \brief Requests mutual exclusion.
        //!
        //! Allows the calling process to attempt to gain mutual exclusion.
        //! When mutual exclusion is granted, the process can safely access the
        //! critical section.
        //!
        //! \retval Error
        //!   Error code indicating the result of the requested operation.
        //!
        //! \b Example: \code
        //! CMutex MyMutex;
        //! MyMutex.lock(TIMEOUT_FOREVER);
        //! ... <access memory> ...
        //! MyMutex.unlock();
        //! \endcode
        virtual TERROR unlock(void) = 0;

    };

  } // namespace code_sheriff

#endif // dIMUTEX_H_
